Viewpoint Guidelines

To avoid performance issues, some guidelines must be followed.

Use representation descriptor instead of representation

When an extension needs to retrieve representations (representation targeted by an element, representation per kind, representation that will be visible in documentation...) or need to store additional information about representations, please use their representation descriptors as much as possible instead of using/storing it in the representation.

Indeed, in a Team for Capella context, a representation is not loaded until it is accessed through descriptor.getRepresentation() (which is the case when the user opens a representation), only its descriptor is. Descriptor may contains the required information that fulfill your needs about representations without have to load the content of the representation and can also be used to store information about it.

Please also refer to Capella Release Notes.

Diagram extensions

Expressions in .odesigns

For performance reasons, when writing expressions in .odesigns it is recommended to:

• Use Java Services for heavy operations.
• Use AQL expressions for light operations.
• The use of Acceleo 2 is NOT supported by default and NOT recommended.

Semantic Candidate Expression

This expression called at each diagram refresh should be the most efficient possible. It can be computed based on the displayed graphical elements using the variable *diagram*. When 'Import Mapping' are used, please ensure that semantic candidate expression has been updated accordingly to the semantic candidate expression of the imported mapping

Create Generic Viewpoints

Create Generic Viewpoints using:

• Sirius capability to extends several diagrams at one time with regular expressions extensions
• Diagram Styles Customization Feature allowing to customize the style of elements based on expression. (for instance, on all "Functions called 'Deprecated'", set color as gray)

Migrating your Viewpoints

From one Version to another the Capella Metamodel can evolve and its existing classes can be modified or removed.

If your Viewpoint Metamodel has any dependencies to the parts of the Capella Metamodel that evolved, then it is necessary to migrate your viewpoint. Here are the three steps that will enable you to do so:

1. Migrate your existing source code. You need to ensure that your code compiles in regards to the new changes, so a rebuild of your viewpoint is necessary.
2. Since Metamodel URIs change from one version to another it is imperative that you replace all obsolete URIs with the new ones. Most of the time it is only a version change, for example the http://www.polarsys.org/capella/core/pa/1.2.0#/ URI for Capella 1.2.0 should be replaced with http://www.polarsys.org/capella/core/pa/1.3.0#/ for Capella 1.3.0.
3. If you inherit from Metamodel classes that changed in the current version, then a migration of the models that use your viewpoint is necessary. This means that you need to contribute to the Capella Migration mechanism. Please refer to the section bellow for more details.

Contributing to the Capella Migration mechanism

Imagine that your viewpoint metamodel inherits from class A. In the new Capella version class A becomes abstract and two new classes B and C inherit from it. This means that all instances in your model that reference class A are obsolete and erroneous, since this class is no longer instantiable.

In this scenario your viewpoint needs to contribute to the native Migration mechanism and replace all the references to class A with references to class B or C. This will allow existing models to become compatible with your viewpoint by simply migrating them.

A good starting point is the org.polarsys.capella.core.data.migration plugin that contains migration examples for the current version of Capella and especially the AbstractMigrationContribution class that you will need to extend in order to add your custom migration logic.

Avoid EObject.eResource calls

On EObject, you have to avoid as much as possible calls to eObject.eResource()

Contribute an ID handler

If your metamodel elements doesn't inherit from org.polarsys.capella.common.data.modellingcore.ModelElement, you have to contribute an Id handler via the extension point "org.polarsys.capella.shared.id.handler.IdHandler" You can simply extend the org.polarsys.capella.shared.id.handler.AbstractIdHandler.